Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle interMedia Java Classes for Servlets and JSP API Reference 10g Release 2 (10.2) Part No. B14300-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## oracle.ord.im
Class OrdHttpJspResponseHandler

`java.lang.Object
oracle.ord.im.OrdHttpResponseHandler
oracle.ord.im.OrdHttpJspResponseHandler`

public class OrdHttpJspResponseHandler
extends OrdHttpResponseHandler

The OrdHttpJspResponseHandler class facilitates the retrieval of media data from Oracle Database, and its delivery to a browser or other HTTP client from a JSP page.

This class inherits the DEFAULT_BUFFER_SIZE field from the OrdHttpResponseHandler class.

An Important Note on JSP Engines
JSP engines are not required to support access to the servlet binary output stream. Therefore, not all JSP engines support the delivery of media data using the OrdHttpJspResponseHandler class.

All media data stored internally in the database using the interMedia types, including text documents stored using the OrdDoc type, is stored using a binary LOB data type. Media data stored in an operating system file outside the database is stored using a BFILE. Therefore, all media data is delivered to the browser through the servlet binary output stream, using the ServletOutputStream class.

All the send methods in the OrdHttpJspResponseHandler class mirror the initial processing of the jsp:forward tag. Specifically, these send methods call the JspWriter clear method to clear the output buffer of the page prior to obtaining the binary output stream. However, JSP engines are not required to support a call to the ServletResponse getOutputStream method from within a JSP page. A JSP engine that does not support this typically throws an IllegalStateException error from the getOutputStream method. However, the exact behavior is implementation-specific.

If your JSP engine does not support access to the binary output stream from within a JSP page, then you must use a servlet to deliver media data. For example, perform one of the following operations:

- Use the jsp:forward tag to forward a media retrieval request to a servlet.
- Construct media retrieval URLs to retrieve the data directly from a servlet.

An Important Note on Return Statements
When delivering media data from a JSP page, a return statement is always required following a call to any of the send methods of the OrdHttpJspResponseHandler class. The return statement is necessary to ensure that no other data is written to the output stream of the JSP page following the media data.

An `if ( true ) { ... return; }` construct can be used to avoid the statement not reachable error that may result from the presence of additional code, generated by the JSP engine, at the end of a compiled page. This construct, which mirrors exactly the code produced by some JSP engines to handle the `<jsp:forward ... >`; directive, is shown in the example provided later in this section.

Note
An interMedia Java object, such as an OrdImage object, is not dependent on the JDBC statement or result set from which it was obtained. However, an interMedia Java object is dependent on the JDBC connection it is using, and on which the SQL statement was executed or from which the result set was obtained. Therefore, having obtained an interMedia Java object from the database, an application must not release the JDBC connection before delivering the media data to the browser.

All the send methods in this class all call the JspWriter clear method to clear the page's output buffer prior to delivering the media. Therefore, the page must use the buffered output model, which is the default.

The following example demonstrates how to use the OrdHttpJspResponseHandler class to retrieve an image from the database and deliver it to a browser. The return statement ensures that the trailing newline characters following the final end tag (represented by a percent mark and right-angle bracket, or `%>`) are not transmitted to the browser as part of the image.

The `if ( true ) { ... return; }` construct is used to avoid the statement not reachable error that would otherwise by produced by this example due to the additional statements, generated by the JSP engine, at the end of the compiled page.

      <%@ page language="java" %>
      <%@ page import="OrdSamplePhotoAlbumBean" %>
      <%@ page import="oracle.ord.im.OrdHttpJspResponseHandler" %>

      <jsp:useBean id="photos" scope="page"
                   class="OrdSamplePhotoAlbumBean"/>
      <jsp:useBean id="handler" scope="page"
                   class="oracle.ord.im.OrdHttpJspResponseHandler"/>

      <%
        //
        // Select the entry from the table using the ID request parameter,
        // then fetch the row.
        //
        photos.selectRowById(request.getParameter("id"));
        if (!photos.fetch())
        {
          response.setStatus(response.SC_NOT_FOUND);
          return;
        }

        //
        // Set the page context for the retrieve request, then retrieve
        // the image from the database and deliver it to the browser. The
        // getImage() method returns an object of type
        // oracle.ord.im.OrdImage.
        //
        if (true)
        {
            handler.setPageContext(pageContext);
            handler.sendImage(photos.getImage());
            return;
        }
      %>

Prerequisites

In order to run interMedia methods for servlets and JSP, you will need to import classes from the oracle.ord.im package into your Java file.

You may also need to import classes from the following Java packages:

     java.sql.
     java.io.
     javax.servlet.
     javax.servlet.http.
     oracle.jdbc.
     oracle.sql.

Field Summary

Fields inherited from class oracle.ord.im.OrdHttpResponseHandler
`DEFAULT_BUFFER_SIZE`

Constructor Summary
`OrdHttpJspResponseHandler()` Creates an OrdHttpJspResponseHandler object to handle the response to a media retrieval request.
`OrdHttpJspResponseHandler(javax.servlet.jsp.PageContext pageContext)` Creates an OrdHttpJspResponseHandler object to handle the response to a media retrieval request, and specifies the PageContext object for the response handler.

Method Summary
`void` | `sendAudio(oracle.ord.im.OrdAudio audio)` Retrieves an audio clip from an OrdAudio object and delivers it to the browser.
`void` | `sendDoc(oracle.ord.im.OrdDoc doc)` Retrieves media data from an OrdDoc object and delivers it to the browser.
`void` | `sendImage(oracle.ord.im.OrdImage image)` Retrieves an image from an OrdImage object and delivers it to the browser.
`void` | `sendResponse()` Builds an HTTP response header, then retrieves the contents of the media data from the database and delivers it to the browser.
`void` | `sendResponse(java.lang.String contentType, int length, oracle.sql.BFILE bfile, java.sql.Timestamp lastModified)` Builds the HTTP response header, then retrieves the contents of the BFILE from the database and delivers it to the browser.
`void` | `sendResponse(java.lang.String contentType, int length, oracle.sql.BLOB blob, java.sql.Timestamp lastModified)` Builds the HTTP response header, then retrieves the contents of the BLOB from the database and delivers it to the browser.
`void` | `sendResponse(java.lang.String contentType, int length, java.io.InputStream in, java.sql.Timestamp lastModified)` Builds the HTTP response header, then retrieves the contents of the InputStream object and delivers it to the browser.
`void` | `sendVideo(oracle.ord.im.OrdVideo video)` Retrieves a video clip from an OrdVideo object and delivers it to browser.
`void` | `setPageContext(javax.servlet.jsp.PageContext pageContext)` Specifies the PageContext object for this response handler.

Methods inherited from class oracle.ord.im.OrdHttpResponseHandler
`sendResponseBody, sendResponseBody, sendResponseBody, setBufferSize, setEncodeHtml, setHeader, setHeader, setHeader, setMedia, setMedia, setMedia, setMedia, setServletRequest, setServletResponse`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### OrdHttpJspResponseHandler

    public OrdHttpJspResponseHandler()

  Creates an OrdHttpJspResponseHandler object to handle the response to a media retrieval request. The application must subsequently specify the PageContext object by calling the `setPageContext(javax.servlet.jsp.PageContext)` method.

  The default constructor is typically invoked implicitly when the OrdHttpJspResponseHandler class is used as a JavaBean.

### OrdHttpJspResponseHandler

    public OrdHttpJspResponseHandler(javax.servlet.jsp.PageContext pageContext)

  Creates an OrdHttpJspResponseHandler object to handle the response to a media retrieval request, and specifies the PageContext object for the response handler.
Parameters:
  `pageContext` - an object of type `PageContext`.

Method Detail

### setPageContext

    public void setPageContext(javax.servlet.jsp.PageContext pageContext)

  Specifies the PageContext object for this response handler. You must call this method before calling any of the send methods if you did not specify the PageContext object in the constructor.
  Parameters:
    `pageContext` - an object of type `PageContext`.

### sendImage

    public void sendImage(oracle.ord.im.OrdImage image)
                   throws javax.servlet.ServletException,
                          java.sql.SQLException,
                          java.io.IOException

  Retrieves an image from an OrdImage object and delivers it to the browser.

  This method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers. This method calls the JspWriter clear method to clear the output buffer of the page prior to delivering the media. Therefore, the page must use the buffered output model, which is the default.

  This method extends and overrides the OrdHttpResponseHandler sendImage(OrdImage) method. See the `OrdHttpResponseHandler.sendImage(OrdImage)` method for information about this method in the base class.

  Overrides:
    `sendImage` in class `OrdHttpResponseHandler`
  Parameters:
    `image` - an object of type `oracle.ord.im.OrdImage`.
  Throws:
    `java.lang.IllegalStateException` - if PageContext has not been specified.
    `OrdHttpResponseException` - if the source type is not recognized.
    `javax.servlet.ServletException` - if an error occurs accessing the binary output stream.
    `java.sql.SQLException` - if an error occurs obtaining an InputStream object to read the media data.
    `java.io.IOException` - if an error occurs reading the media data.

### sendAudio

    public void sendAudio(oracle.ord.im.OrdAudio audio)
                   throws javax.servlet.ServletException,
                          java.sql.SQLException,
                          java.io.IOException

  Retrieves an audio clip from an OrdAudio object and delivers it to the browser.

  This method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers. This method calls the JspWriter clear method to clear the output buffer of the page prior to delivering the audio clip. Therefore, the page must use the buffered output model, which is the default.

  This method extends and overrides the OrdHttpResponseHandler sendAudio(OrdAudio) method. See the `OrdHttpResponseHandler.sendAudio(OrdAudio)` method for information about this method in the base class.

  Overrides:
    `sendAudio` in class `OrdHttpResponseHandler`
  Parameters:
    `audio` - an object of type `oracle.ord.im.OrdAudio`.
  Throws:
    `java.lang.IllegalStateException` - if PageContext has not been specified.
    `OrdHttpResponseException` - if the source type is not recognized.
    `javax.servlet.ServletException` - if an error occurs accessing the binary output stream.
    `java.sql.SQLException` - if an error occurs obtaining an InputStream object to read the media data.
    `java.io.IOException` - if an error occurs reading the media data.

### sendVideo

    public void sendVideo(oracle.ord.im.OrdVideo video)
                   throws javax.servlet.ServletException,
                          java.sql.SQLException,
                          java.io.IOException

  Retrieves a video clip from an OrdVideo object and delivers it to browser.

  This method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers. This method calls the JspWriter clear method to clear the output buffer of the page prior to delivering the video clip. Therefore, the page must use the buffered output model, which is the default.

  This method extends and overrides the OrdHttpResponseHandler sendVideo(OrdVideo) method. See the `OrdHttpResponseHandler.sendVideo(OrdVideo)` method for information about this method in the base class.

  Overrides:
    `sendVideo` in class `OrdHttpResponseHandler`
  Parameters:
    `video` - an object of type `oracle.ord.im.OrdVideo`.
  Throws:
    `java.lang.IllegalStateException` - if PageContext has not been specified.
    `OrdHttpResponseException` - if the source type is not recognized.
    `javax.servlet.ServletException` - if an error occurs accessing the binary output stream.
    `java.sql.SQLException` - if an error occurs obtaining an InputStream object to read the media data.
    `java.io.IOException` - if an error occurs reading the media data.

### sendDoc

    public void sendDoc(oracle.ord.im.OrdDoc doc)
                 throws javax.servlet.ServletException,
                        java.sql.SQLException,
                        java.io.IOException

  Retrieves media data from an OrdDoc object and delivers it to the browser.

  This method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers. This method calls the JspWriter clear method to clear the output buffer of the page prior to delivering the media. Therefore, the page must use the buffered output model, which is the default.

  This method extends and overrides the OrdHttpResponseHandler sendDoc(OrdDoc) method. See the `OrdHttpResponseHandler.sendDoc(OrdDoc)` method for information about this method in the base class.

  Overrides:
    `sendDoc` in class `OrdHttpResponseHandler`
  Parameters:
    `doc` - an object of type `oracle.ord.im.OrdDoc`.
  Throws:
    `java.lang.IllegalStateException` - if PageContext has not been specified.
    `OrdHttpResponseException` - if the source type is not recognized.
    `javax.servlet.ServletException` - if an error occurs accessing the binary output stream.
    `java.sql.SQLException` - if an error occurs obtaining an InputStream object to read the media data.
    `java.io.IOException` - if an error occurs reading the media data.

### sendResponse

    public void sendResponse(java.lang.String contentType,
                             int length,
                             oracle.sql.BLOB blob,
                             java.sql.Timestamp lastModified)
                      throws javax.servlet.ServletException,
                             java.sql.SQLException,
                             java.io.IOException

  Builds the HTTP response header, then retrieves the contents of the BLOB from the database and delivers it to the browser.

  This method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers. This method calls the JspWriter clear method to clear the output buffer of the page prior to delivering the media. Therefore, the page must use the buffered output model, which is the default.

  This method extends and overrides the OrdHttpResponseHandler sendResponse(String, int, BLOB, Timestamp) method. See the `OrdHttpResponseHandler.sendResponse(String, int, BLOB, Timestamp)` method for information about this method in the base class.

  Overrides:
    `sendResponse` in class `OrdHttpResponseHandler`
  Parameters:
    `contentType` - a `String` that specifies the MIME type of the content.
    `length` - an integer (`int`) that specifies the length of the data.
    `blob` - an object of type `oracle.sql.BLOB` from which the media data is retrieved.
    `lastModified` - a java.sql.Timestamp object that specifies the date and time when the data was last modified, or `null` if no last modified date and time are available.
  Throws:
    `java.lang.IllegalStateException` - if PageContext has not been specified.
    `javax.servlet.ServletException` - if an error occurs accessing the binary output stream.
    `java.sql.SQLException` - if an error occurs obtaining an InputStream object to read the media data.
    `java.io.IOException` - if an error occurs reading the media data.
    `java.lang.IllegalArgumentException` - if the length is negative.

### sendResponse

    public void sendResponse(java.lang.String contentType,
                             int length,
                             oracle.sql.BFILE bfile,
                             java.sql.Timestamp lastModified)
                      throws javax.servlet.ServletException,
                             java.sql.SQLException,
                             java.io.IOException

  Builds the HTTP response header, then retrieves the contents of the BFILE from the database and delivers it to the browser.

  This method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers. This method calls the JspWriter clear method to clear the output buffer of the page prior to delivering the media. Therefore, the page must use the buffered output model, which is the default.

  This method extends and overrides the OrdHttpResponseHandler sendResponse(String, int, BFILE, Timestamp) method. See the `OrdHttpResponseHandler.sendResponse(String, int, BFILE, Timestamp)` method for information about this method in the base class.

  Overrides:
    `sendResponse` in class `OrdHttpResponseHandler`
  Parameters:
    `contentType` - a `String` that specifies the MIME type of the content.
    `length` - an integer (`int`) that specifies the length of the data.
    `bfile` - an object of type `oracle.sql.BFILE` from which the media data is retrieved.
    `lastModified` - a java.sql.Timestamp object that specifies the date and time when the data was last modified, or `null` if no last modified date and time are available.
  Throws:
    `java.lang.IllegalStateException` - if PageContext has not been specified.
    `javax.servlet.ServletException` - if an error occurs accessing the binary output stream.
    `java.sql.SQLException` - if an error occurs obtaining an InputStream object to read the media data.
    `java.io.IOException` - if an error occurs reading the media data.
    `java.lang.IllegalArgumentException` - if the length is negative.

### sendResponse

    public void sendResponse(java.lang.String contentType,
                             int length,
                             java.io.InputStream in,
                             java.sql.Timestamp lastModified)
                      throws javax.servlet.ServletException,
                             java.io.IOException

  Builds the HTTP response header, then retrieves the contents of the InputStream object and delivers it to the browser.

  This method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers. This method calls the JspWriter clear method to clear the output buffer of the page prior to delivering the media. Therefore, the page must use the buffered output model, which is the default.

  This method extends and overrides the OrdHttpResponseHandler sendResponse(String, int, InputStream, Timestamp) method. See the `OrdHttpResponseHandler.sendResponse(String, int, InputStream, Timestamp)` method for information about this method in the base class.

  Overrides:
    `sendResponse` in class `OrdHttpResponseHandler`
  Parameters:
    `contentType` - a `String` that specifies the content's MIME type.
    `length` - an integer (`int`) that specifies the length of the data.
    `in` - an InputStream object from which the media data is retrieved.
    `lastModified` - a java.sql.Timestamp object that specifies the date and time when the data was last modified, or `null` if no last modified date and time are available.
  Throws:
    `java.lang.IllegalStateException` - if PageContext has not been specified.
    `javax.servlet.ServletException` - if an error occurs accessing the binary output stream.
    `java.io.IOException` - if an error occurs reading the media data.
    `java.lang.IllegalArgumentException` - if the length is negative.

### sendResponse

    public void sendResponse()
                      throws javax.servlet.ServletException,
                             java.sql.SQLException,
                             java.io.IOException

  Builds an HTTP response header, then retrieves the contents of the media data from the database and delivers it to the browser. This method is to be called after the setMedia method in order to get media data. This method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers. This method calls the JspWriter clear method to clear the output buffer of the page prior to delivering the data. Therefore, the page must use the buffered output model, which is the default.
  Overrides:
    `sendResponse` in class `OrdHttpResponseHandler`
  Throws:
    `java.lang.IllegalStateException` - if PageContext has not been specified.
    `OrdHttpResponseException` - if the source type is not recognized.
    `javax.servlet.ServletException` - if an error occurs accessing the binary output stream.
    `java.sql.SQLException` - if an error occurs obtaining an InputStream object to read the media data.
    `java.io.IOException` - if an error occurs reading the media data.

Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle interMedia Java Classes for Servlets and JSP API Reference 10g Release 2 (10.2) Part No. B14300-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 1999, 2005, Oracle. All rights reserved.